fix(objectql, lint): synced objects are told to drop write verbs, not to open userActions - #33517

Requested by Leehom · project thread

domain:spec#1 · os-project-manager · session_01FEkQ5p6qE7Nt8wpjSGLqiC

Fixes #32134

Clause-②: no
Metadata-protocol: none

维护者速读

• 改了什么:managedBy: 'synced' 对象上,注册时剥除写动词的告警和 lint 规则 object/managed-api-method-unaffordable 的报错/修复行,不再让作者去 userActions 打开写权限,改为:列出要从 enable.apiMethods 删掉的动词,写入走声明的 action(ADR-0153 D5)。os explain 多一段说明。其他 bucket 的文字逐字不变。
• 为什么改:feat(spec)!: one-way sync-in, the spec half — datasource source, paging and delete policy keys, the pull refusals, and the synced bucket (ADR-0153) #32118 之后,synced 对象上 userActions 打开写动词会在 parse 时被拒(ADR-0153 D4)。旧文案让作者去改 userActions,改完构建又报错,两条信息互相矛盾,作者无路可走。
• 风险与回滚:只改文案,剥除行为、规则判定、规则 id/严重度/path、schema 都不变。回滚即还原本 PR。
• 先看:packages/lint/src/validate-managed-api-methods.ts 的 writeLocked 分支;packages/objectql/src/registry.ts reconcileManagedApiMethods 的 remedy。
• 两分钟验证:pnpm --filter @objectstack/lint exec vitest run src/validate-managed-api-methods.test.ts,预期 15 条全绿(含 synced 的两条新钉子)。
• 需要你做的:无,席位落地。

What changes

Both sentences branch on MANAGED_BY_WRITE_LOCKED_BUCKETS (@objectstack/spec/data, today synced alone), the same set the parse refusal (refuseWriteLockedUserActions), resolveCrudAffordances and the core /me/permissions clamp already read, so the remedy text and the refusal can never disagree about which bucket is locked.

• packages/objectql/src/registry.ts reconcileManagedApiMethods. On a write-locked bucket the warning's remedy reads: "userActions cannot open a write on this bucket (ADR-0153 D4): remove [VERBS] from enable.apiMethods and send writes through a declared action (ADR-0153 D5)." Every other bucket keeps "Declare userActions to open a verb the object legitimately takes from a user context." The rest of the line (object, bucket, stripped and kept verbs, the lint rule id) and the strip are unchanged.
• packages/lint/src/validate-managed-api-methods.ts (object/managed-api-method-unaffordable). On a write-locked bucket the verdict reads "enable.apiMethods advertises [VERBS], which managedBy: 'synced' refuses, and userActions cannot open a write there, so the registry strips them", and the fix line reads "Remove [VERBS] from enable.apiMethods, and send writes through a declared action". Every other bucket keeps "(needs userActions …)" and both ways out. Rule id, severity, where, path and the verdict itself are unchanged.
• packages/lint/src/rule-explanations.ts. os explain object/managed-api-method-unaffordable gains one paragraph: on synced userActions cannot open a write (ADR-0153 D4), so the fix line offers only the removal, and a write goes through a declared action (ADR-0153 D5).
• .changeset/32134-synced-remedy-text.md: @objectstack/objectql patch, @objectstack/lint patch. Both packages ship dist/ (files: [dist, README.md, CHANGELOG.md]); the new text is in packages/objectql/dist/index.js and packages/lint/dist/index.js after build.

File surface. The order named managed-api-affordance.ts's describeManagedApiMethodConflicts as the lint sentence's source. Measured on origin/main f068cde8: the lint rule no longer reads it (it builds its own message and hint, validate-managed-api-methods.ts L110-114, and its CHANGELOG records the switch), and the helper has no production caller, only its own test. The seat amended the claim's surface to the lint rule, its test and the explain paragraph, and ruled the spec helper out of this PR (no parameter added to an export nobody calls). No packages/spec file moves, so there is no spec changeset.

Tests

• packages/objectql/src/registry.test.ts: a synced fixture pins the whole warning line; a control on engine-owned pins today's line byte for byte.
• packages/lint/src/validate-managed-api-methods.test.ts: a synced fixture pins the whole verdict, and one with every write verb pins the whole fix line (and that it never says userActions); the existing exact pins on platform (verdict) and better-auth (fix line) are the controls and are unchanged. The explanation's fact list gains ADR-0153 D4 and ADR-0153 D5. Both synced cases are recorded by the file's one-line, at-most-200-characters checks.

registry.ts: "const remedy = MANAGED_BY_WRITE_LOCKED_BUCKETS.has(managedBy)" -> "const remedy = false"
  anchor x1 -> x0, replacement x0 -> x1, blob eb3b6f1d1036 -> 856148d4ab92
  x on a synced object, the warning names the verbs to drop and a declared action, never userActions
  Tests 1 failed | 106 passed (107)
  ok restored: blob == HEAD (eb3b6f1d1036) and `git diff HEAD` is empty

validate-managed-api-methods.ts: "const writeLocked = MANAGED_BY_WRITE_LOCKED_BUCKETS.has(bucket);" -> "const writeLocked = false;"
  blob 682b98ae055e -> 6f513b203589
  x on a synced object, the verdict says userActions cannot open a write, never "needs userActions"
  x on a synced object, the fix line offers only the removal and a declared action
  Tests 2 failed | 13 passed (15)
  ok restored: blob == HEAD (682b98ae055e) and `git diff HEAD` is empty

Acceptance notes

• The spec helper still says "(needs userActions …)". describeManagedApiMethodConflicts (packages/spec/src/data/managed-api-affordance.ts L142-150) takes only the conflicts, which carry no bucket, and nothing in the platform calls it any more. Left as it is by the seat's ruling; reported to the seat to card.
• No generated reference or skill renders either sentence. git grep for the rule id and for "Declare userActions" over skills/, content/ and docs/ answers nothing, so nothing is regenerated.

Verification

On head f127667d (branch claude/project-thread-88rfao, merge base origin/main f068cde8), each exit code captured before any pipe:

• pnpm --filter @objectstack/objectql --filter @objectstack/lint test (under the verify lock): exit 0; lint Test Files 210 passed (210), Tests 8973 passed (8973); objectql Test Files 595 passed (595), Tests 13013 passed (13013).

• pnpm --filter @objectstack/objectql --filter @objectstack/lint typecheck (tsc --noEmit plus check:test-typecheck over tsconfig.test.json): exit 0, no new pinned signature ("39 file(s) / 233 error(s) / 64 pinned signature(s) held" for objectql, "2 file(s) / 6 error(s) / 2 pinned signature(s) held" for lint).

• eslint --no-inline-config on the five changed source and test files: exit 0.

• Derived gates (node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack, 73 families): 72 exit 0; pnpm check:dual-build-cjs-loads exit 3 PREREQUISITE NOT MET (needs every package's dist/), NOT MEASURED, CI runs it. --ran: "73 derived famil(ies) accounted for — 72 run, 1 NOT-MEASURED".

• dispatch-gates --tier: no path-derived mandate; 121 changed lines, under the 3000 threshold; no governed surface.

• origin/main moved to e40cd1e2 after the run; none of its commits touches the changed files or object.zod.ts.

• CI families are read from this PR's check-runs, not re-run here.

🤖 Generated with Claude Code

https://claude.ai/code/session_01FEkQ5p6qE7Nt8wpjSGLqiC